home *** CD-ROM | disk | FTP | other *** search
/ Tech Arsenal 1 / Tech Arsenal (Arsenal Computer).ISO / tek-21 / qwhite.zip / XDI.TEC < prev    next >
Text File  |  1992-03-09  |  9KB  |  152 lines
  1. ID:XD XDI Specification for DESQview
  2. Quarterdeck Technical Note #182
  3. by Daniel Travison
  4. last revision:  2 March 1992
  5.  
  6. Q: How can my device driver/TSR work better with DESQview?
  7.  
  8. DESQview's External Device Interface
  9.  
  10.      DESQview version 2.26 (and above), can issue informative messages to 
  11. third party software in order for that software to monitor certain DESQview 
  12. operations such as starting a task or swapping out a process.  These messages 
  13. can be useful for determining when to allocate/deallocate resources (e.g., 
  14. memory) on a process by process basis, communicating with tasks running within 
  15. DESQview, rescheduling tasks, tracking DESQview's task switching, etc.
  16.      DESQview provides this information through the External Device Interface 
  17. (XDI) - Quarterdeck's specification for communicating with external drivers.
  18.      An XDI driver may be implemented either as a DOS device driver (loaded by 
  19. CONFIG.SYS), a Terminate and Stay Resident program (TSR) loaded before or 
  20. after DESQview, or as a DESQview shared program (shared among several 
  21. processes).  For the rest of this documentation, the term 'driver' will 
  22. normally refer to a program that uses the XDI, irrespective of its method of 
  23. implementation (device driver, TSR, or shared program).  Also, any number of 
  24. XDI drivers can be loaded.  When DESQview starts, it simply attaches itself to 
  25. the XDI chain and starts sending XDI messages to previously loaded XDI 
  26. drivers.
  27.      Within the XDI, there are 15 subfunctions (messages).  Fourteen of these 
  28. messages inform the driver what action DESQview has just performed or is about 
  29. to perform.  Your driver can choose to ignore the message and pass it on to 
  30. the next driver in the chain, perform/schedule work based on the message, or 
  31. save information for later use (e.g., the current mapping context). 
  32.  
  33.         XDI_CHECK_PRESENCE      Check for XDI driver presence     
  34.         XDI_RESERVED_SUBFUNC    XDI driver custom subfunction     
  35.         XDD_START_DV            DV system initialization complete 
  36.         XDI_END_DV              DV system termination             
  37.         XDI_START_PROC          DV process creation
  38.         XDI_END_PROC            DV process termination            
  39.         XDI_START_TASK          Task creation
  40.         XDI_END_TASK            Task termination
  41.         XDI_SAVE_STATE          Task state save
  42.         XDI_RESTORE_STATE       Task state restore
  43.         XDI_KEYBOARD            Change of keyboard focus          
  44.         XDI_PROCESS_DVP         Processing of DVP file complete   
  45.         XDI_SWAPPING_OUT        Swap out of DV process            
  46.         XDI_SWAPPED_IN          Swap in of DV process             
  47.         XDI_FAILED_DVP          DV process creation failure
  48.  
  49.      An XDI driver can schedule second level handlers to make API calls, 
  50. collect data, transfer data, dispatch tasks, perform 
  51. initialization/termination when DESQview is started, and quit.
  52.  
  53.      The fifteenth subfunction, XDI_RESERVED_SUBFUNC provides a method for 
  54. applications to communicate with your driver without needing to grab an 
  55. additional interrupt vector.   Additionally, this interface does not require 
  56. DESQview to be loaded.  In other words, if DESQview is not loaded, the 
  57. application and XDI driver will still be able to communicate.
  58.  
  59. Q: When would I want to use the XDI specification?
  60.  
  61.      If your driver needs to write into an application's address space then 
  62. you need to ensure that the address is valid when you perform the write.  
  63. (e.g., The DOS SETDTA call requires the caller provide a pointer to a buffer 
  64. that will be filled in at a later time.  A communications handler might use a 
  65. similar interface but perform the update at interrupt time.)  With DESQview, 
  66. this buffer may get mapped in and out to accomodate running multiple programs. 
  67.  If your driver attempts to write into this buffer when DESQview has mapped 
  68. some other application into it (e.g., at interrupt time) then you will be 
  69. corrupting the unknown application.  The XDI allows your driver to determine 
  70. when the write operation is safe or specifically request that DESQview map the 
  71. application in to allow safe access to the application's address space.
  72.      Another example is the use of Multiplex boards.  Multiplex boards have 
  73. two important features:  One, they provide access to multiple external devices 
  74. (e.g., modems) using a single IRQ; and, two, they provide a software interface 
  75. for applications.  The software interface removes the need for the application 
  76. to manage the hardware directly.  In the case of a multiplex board providing 
  77. additional serial ports, the user will often want to run more than one program 
  78. at a time to take advantage of extra serial ports (e.g., A number of BBS 
  79. systems provide the option for running multiple copies at once and also 
  80. support drivers for multiplex boards.)  The programmer writing the driver will 
  81. need to accomodate simultaneous access to the driver as well as provide a 
  82. reliable software interface.
  83.  
  84. Other issues addressed by the XDI:
  85.  
  86.   1) Allocation of a software interrupt to allow the application to 
  87. communicate with the driver.  
  88.      With more and more device drivers and TSRs available, it is important to 
  89. prevent possible conflicts with other software.  The XDI specification uses 
  90. the multiplex interrupt (INT 2Fh) as a basis for sharing a single interrupt 
  91. using a well defined interface.  Once the application has 'logged' itself with 
  92. the driver (XDI_RESERVED_SUBFUNC), the driver may provide an ID for future use 
  93. or simply manage it internally, based on which process DESQview has mapped in 
  94. when the software interrupt is called.  This portion of the interface 
  95. functions in the same manner whether DESQview is loaded or not.  When DESQview 
  96. is not present, the driver does not need to be concerned with the mapping 
  97. context.
  98.   2) Allocation of memory/application that needs to be accessible at any given 
  99. time. 
  100.      This could be a buffer for incoming data.  Normally, the driver would 
  101. need to allocate all of the memory it needs during its initialization code.  
  102. DESQview allows an XDI driver to allocate COMMON memory (memory that does not 
  103. get mapped out) during an XDI call.  This allows the driver to allocate only 
  104. the memory necessary when a new application starts.  It DESQview is not 
  105. present, the application would allocate a buffer out of its own data space.  A 
  106. check for DESQview would be all that is necessary for the application to 
  107. determine whether it needs to allocate a buffer or allow the driver to 
  108. allocate it from COMMON memory.
  109.  
  110.   3) Preventing re-entrancy during non-reentrant sections of code. 
  111.      In a perfect world, all of your driver's code would be re-entrant. Since 
  112. this may not be practical without unreasonable code or CPU overhead, the XDI 
  113. driver can temporarily suspend multitasking to perform its critical work.  
  114. This does not mean that the XDI allows you to write non-re-entrant handlers 
  115. but it can solve some sticky issues that arise when you need to support 
  116. simultaneous access.
  117.  
  118.   4) The application cannot keep up with the data rate.  
  119.      There will be times when the application cannot empty the driver's buffer 
  120. faster than the driver can fill it.  The user may have started up a few extra 
  121. applications and the CPU is too slow to give everyone enough time.  The XDI 
  122. driver could consider some percentage of the buffer as a threshold.  When this 
  123. threshold is reached the driver can temporarily override DESQview's dispatcher 
  124. and force the application's 'buffer management' routine to execute at the next 
  125. context switch.
  126.  
  127.   5) The driver needs to know when the application exits to allow proper 
  128. cleanup. 
  129.      Normally, the application itself would call the driver to initiate 
  130. cleanup.  Occasionally this will not occur (e.g., the user shut down the 
  131. application via DESQview's Close Window menu selection).  DESQview notifies 
  132. the XDI driver when a process ends to allow the driver to determine if it 
  133. needs to perform any cleanup for the process.
  134.      There are other areas where an XDI driver could be of use:  resource 
  135. tracking on a process-by-process basis, modifying the .DVP when each process 
  136. starts, allocating additional system memory for the process at startup, 
  137. tracking CPU usage, or even displacing DESQview's dispatcher.
  138.  
  139. Q: How do I find out more about the XDI?
  140.  
  141. DESQview's XDI is fully documented in Quarterdeck's API Reference Manual 
  142. (versions 1.20 and later).  Included is a sample XDI driver (POKEXDI.ASM) that 
  143. can be used as a template for designing your own.  Contact Quarterdeck for 
  144. information on obtaining a copy of our API Reference Manual or upgrading and 
  145. older API Reference Manual.
  146.  
  147.   ************************************************************************
  148.   *This technical note may be copied and distributed freely as long as it*
  149.   *is distributed in its entirety and it is not distributed for profit.  *
  150.   *        Copyright (C) 1990-2 by Quarterdeck Office Systems            *
  151.   ************************ E N D   O F   F I L E *************************
  152.